home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 2: CDPD 1 / Almathera Ten on Ten - Disc 2: CDPD 1.iso / pd / 276-300 / 288 / scripit / usage.doc < prev    next >
Text File  |  1995-03-14  |  10KB  |  274 lines
  1.                     Scripit  --  The Intuition Script Language
  2.                     ==========================================
  3.  
  4.  
  5.                                By: Khalid Aldoseri
  6.                                -------------------
  7.  
  8. NOTE:
  9.  
  10. You should read the 'Reference.DOC' file and the 'Examples' file for more
  11. information about Scripit.  This doc file only tells you how to run the
  12. script runner, recorder and lister.  It does NOT help you at all in
  13. writing scripts.  All the details of each command, Scripit's language
  14. structure and examples are in the files mentioned above.
  15.  
  16.  
  17.  
  18. Scripit:  The script executor:
  19. ------------------------------
  20.  
  21. 'Scripit' is the program that runs Scripit scripts.  Its operation is very
  22. simple.
  23.  
  24. To use Scripit just issue the following command from CLI:
  25.  
  26.         Scripit  scriptfilename
  27.  
  28. The format of the Scripit scriptfile should be normal text lines ending with
  29. a carriage return.
  30.  
  31.     Format: Scripit [flags] [scriptfile] [arg1] [arg2] ... [arg9]
  32.  
  33.      Flags: -v  Turns on Verbose mode.
  34.             -d  Turns on Debug mode.
  35.             -x  Loads Scripit Resident Arexx mode.
  36.                 Format: Scripit -x [portname]
  37.                 Where PortName is the portname Scripit will be referenced
  38.                 by from ARexx.
  39.             -c  Compile Script.
  40.                 Format: Scripit -c [input file] [output file]
  41.             -w  Disable Warnings.
  42.  
  43. Scripit's commands control other programs by manipulating their menus, gadgets
  44. windows, and screens.  The programs being controlled do not need any special
  45. ports as all the messages they receive are simulated Intuition messages.  In
  46. fact, the programs don't even recognize that it isn't Intuition talking to
  47. them!
  48.  
  49. You can also run Scripit from WB by clicking on its icon and then selecting
  50. the script file from the file requester.  (The file requester will first
  51. search for a directory called Scripit:.  If it doesn't find it, it will
  52. use the current directory.)
  53.  
  54. The arguments entered after the script name are accessible via the system
  55. variables $arg[1] to $arg[9].  (see Reference.DOC)
  56.  
  57. Once a script has started running you can abort it at any time by pressing
  58. the control key and the left mouse button at the same time.  You can also
  59. pause the script by using the left shift+left mouse button, and to resume
  60. execution, use right shift+left mouse button.  More details in Reference.DOC.
  61.  
  62.  
  63. Compiling Scripts:
  64. ------------------
  65.  
  66. Scripit can compile scripts into a special format that is usually around
  67. 30%-50% smaller in size than the original file and runs a lot quicker.
  68. These files are automatically identified by Scripit.
  69.  
  70. To compile a script:
  71.     Scripit -c [inputfile] [outputfile]
  72.  
  73.     e.g.  Scripit -s Access Acc
  74.     This creates a compiled file called 'Acc'.
  75.  
  76. To run a compiled script:
  77.  
  78.     Scripit Acc
  79. OR  Xit Acc
  80.  
  81.     'Xit' is a special version of Scripit that _only_ runs compiled files.
  82. It is a lot smaller in size than Scripit, which allows it to load a lot
  83. faster.  If you try to execute a non-compiled script with 'Xit' it will
  84. just quit.
  85.  
  86. Note: Compiled Scripit files can be identified by the first four bytes
  87.       in the file.  They are 'X' 'I' 'T' '2'.
  88.  
  89.  
  90. When you specify a non-compiled script file name to Scripit, it will
  91. automatically compile it and then run it.  However, if Scripit cannot
  92. read in the whole file at once, (like when using '*' as a file name or
  93. through pipes or if it cannot allocate enough memory to load in the
  94. whole file at once) it will compile and execute it line by line.
  95. Using 'Scripit *' will allow you to enter the 'live mode' where you
  96. can enter commands directly from the console and each command will be
  97. executed one by one as you type them in.
  98.  
  99.  
  100. Using Scripit from Workbench:
  101. -----------------------------
  102.  
  103. To use Scripit from the Workbench just double-click on its icon.  The
  104. file requester will come up allowing you to select a script file to
  105. execute.  You can also auto-invoke a script by double-clicking on
  106. the script file's icon.  Both 'Scripit' and 'Xit' can execute
  107. scripts this way, however 'Xit' doesn't have a file-requester.
  108. You can use any icon file as the script icon as long as it is
  109. a project icon can be used.  Just make sure that the tool name points
  110. to either Scripit (for normal scripts) or Xit (for compiled scripts.)
  111.  
  112.  
  113. Supporting Programs:
  114. --------------------
  115.  
  116. 1.  Recorder:
  117.  
  118.     This is a general Intuition event recorder that records what the user is
  119.     doing and saves it to a file you select.  This saved file is totally
  120.     compatible with Scripit and when run from Scripit it will recreate the
  121.     original user activities as closely as possible.
  122.  
  123.     This is _not_ a keyboard and mouse macro recorder.  It actually records all
  124.     messages going from Intuition to the currently active window.  It will also
  125.     monitor what the active window is, and if it changes Recorder will add the
  126.     necessary commands to change the active window in the script as well.
  127.  
  128.     The concept behind Recorder is that of a utility that helps you in writing
  129.     scripts.  The script files generated by Recorder are normally long-winded
  130.     since Recorder has no way of finding out which actions are necessary and
  131.     which aren't.  It is best to use the scripts generated by Recorder as the
  132.     first step in writing a script, then editing them to make them smaller,
  133.     faster, and maybe even add variables or flow and logic control to them.
  134.  
  135.     The file created by Recorder can be edited as it is a normal script file.
  136.  
  137.     To use Recorder, just run it from CLI:   Recorder scriptfilename
  138.  
  139.     After that do all the 'actions' you want, and when you want to stop the
  140.     recording, send it a Control-C by either clicking into the CLI window and
  141.     pressing Control-C or by using the 'break' command, or by closing its
  142.     window.  (Note: the power LED will flicker as long as it is recording.)
  143.  
  144.     To execute the saved script just use:  Scripit scriptfilename
  145.  
  146.     Recorder has several options.  (Use Recorder ? to see the options.)
  147.  
  148.     Format: Recorder [-flags] [scriptfile]
  149.  
  150.      Flags: -c  Adds comments to script.
  151.             -w  Do not open display window.
  152.             -l  Disable power LED activity meter.
  153.             -n  Use menu & gadget numbers instead of text.
  154.             -t  Disable time recording.
  155.             -m  Disable MouseMoves recording.
  156.             -i  Disable Intuiticks recording.
  157.  
  158.  
  159. 2.  Lister
  160.  
  161.     This is a general screen, window, menu and gadget listing facility that
  162.     will help in identifying the correct names or numbers of the items to be
  163.     controlled.
  164.  
  165.     To use Lister, just run it.  You will get a list of screens in the system.
  166.     You can then see the windows in a specific screen by typing the first few
  167.     letters of the screen name as Lister's first argument.  You can go on to
  168.     specify window, menu, menuitem, subitem, or gadget.  The format is:
  169.  
  170.     Format:  Lister  [screen] [window] [menu] [item] [subitem]
  171.         or:  Lister  [screen] [window] -g [gadget]
  172.  
  173.  
  174.  
  175. 3.  XitLoadWB
  176.  
  177.     This program allows Scripit to control the WorkBench.  Read the doc file
  178.     'Reference.DOC' for details on its usage.
  179.  
  180.  
  181.  
  182. 4.  AutoScript:  The Script AutoScript Maker:
  183.  
  184.     This will take a normal Scripit script file and make it into an auto-
  185.     running script.  i.e.  Instead of typing 'Scripit scriptname' you only
  186.     have to type 'scriptname'.
  187.  
  188.     Command format:
  189.  
  190.     Format: AutoScript <scriptname> [<destination directory>]
  191.  
  192.     Example:
  193.  
  194.     You have a script file in the current directory called 'Shrink'.
  195.  
  196.     Contents of File 'Shrink':
  197.  
  198.           BEGIN
  199.           SELECT ACTIVE
  200.           MOVETO 0,0
  201.           MINSIZE
  202.  
  203.     Using AutoScript, we make it into an auto executing script in S: by the
  204.     following command:
  205.  
  206.     AutoScript Shrink s:
  207.  
  208.     This generates the following script as "s:Shrink" :
  209.  
  210.         .key arg1,arg2,arg3,arg4,arg5,arg6,arg7,arg8,arg9
  211.         Scripit -w s:Shrink "<arg1>" "<arg2>" "<arg3>" "<arg4>"
  212.                             "<arg5>" "<arg6>" "<arg7>" "<arg8>" "<arg9>"
  213.         ;BEGIN
  214.         ;SELECT ACTIVE
  215.         ;MOVETO 0,0
  216.         ;MINSIZE
  217.  
  218.     AutoScript will also set the 's' protect bit on S:Shrink.
  219.  
  220.     The first line gets all the arguments passed to s:Shrink which are
  221.     then passed over to Scripit in the second line.
  222.  
  223.     After doing this, type 'Shrink' from the CLI will automatically
  224.     load Scripit, and then load and execute the script file.
  225.     (When Scripit executes a file, it will ignore the semi-colon
  226.     if its the first character in the line.)  The default destination
  227.     directory is RAM:.  Make sure that the CLI's search path is
  228.     set to the directory that the script file is in.
  229.  
  230.     This example script doesn't use user arguments, but they are still
  231.     handled correctly by AutoScript.
  232.  
  233.     The -w flag is used so that Scripit won't complain on unknown commands.
  234.     (i.e. the first 2 lines of s:Shrink)
  235.  
  236.     NOTES:
  237.  
  238.     - This only works with text script files, not with compiled scripts.
  239.  
  240.     - You need Workbench 1.3 or higher in order to use this facility.
  241.  
  242.     - There is only one known problem with this technique:  #argcount is
  243.       always 9 no matter how many arguments you provide via this method.
  244.  
  245.  
  246. Notes on file requester:
  247.  
  248.     The file requester has two hidden features:
  249.  
  250.     1. click on the right mouse button to get a list of the volume names of
  251.        devices currently in the system.  Click on it again to get the list
  252.        of 'logical' devices, i.e. assigns;
  253.     2. you can resize the file requester, the resize gadget is at the bottom
  254.        of the requester, all across the bottom border.
  255.  
  256.  
  257. All comments, suggestions, bug reports, etc. should be sent to:
  258.  
  259.     Khalid Aldoseri, CIS 75166,2531.
  260.  
  261.  
  262.  
  263.     Many thanks to Vic Wagner for his help with the script language,
  264.     Larry Phillips for coming up with the name 'Scripit', and mostly
  265.     to Brian J. Bartlett for countless hours in conference testing Scripit
  266.     and for lots of great suggestions.
  267.  
  268.     Official support for Scripit is provided on Compuserve in the
  269.     AmigaTech forum, under Section 12:  Other Languages.
  270.  
  271.  
  272.  
  273.                       Copyright 1989  Khalid Aldoseri.
  274.